Parent | Child | Previous | Next
 
Xbasic

a5_number_format Function

Syntax

C a5_number_format(N value,C formatString)

Arguments

valueNumeric

The numeric value to format as a string.

formatStringCharacter

The format string. See discussion below.

Returns

resultCharacter

Returns the number as a string using the specified format.

Description

Formats a number using the number formatter in the Alpha Javascript library.

Discussion

The a5_number_format() function converts a numeric value to a string. The string to generate is specified as a number format string. The number format string contains special characters that define how the number should be presented, including options for decimal places, zero padding, the type of thousands and decimal separators to use, and more.

Number format strings can contain up to three custom definitions to format positive, negative, and zero values separately. Multiple formats are specified as a semi-colon ";" delimited list. For example:

format1;format2
format1;format2;format3

where format1, format2, and format3 are number format string expressions.

The way a given format in the format string is selected is based on either its location in the string, or by an optional condition.

If the format string doesn't contain any conditions then the first format will be used for a positive value, the second for a negative, and the third for a zero value.

Conditions can be used in formats by adding the if(test) expression to the start of the string. The test can reference the placeholder n, which is the number to format. For example:

dim format as c = "if(n>999999999)=(###) ###-####;=###-####"
? a5_number_format(1234567890, format)
= "(123) 456-7890"

? a5_number_format(1234567,format)
= "123-4567"

This is an example of a multi-format string that the will return numbers greater than 999999999 as a 10 digit phone number mask and number less than 999999999 as a 7 digit phone number mask.

You can also optionally process a number before it is formatted by adding =(expression) to the end of a format string. The expression can also use the placeholder n, which is the number to passed to the a5_number_format() function. For example:

dim format as c = "##0.00 %=(n*100)"

? a5_number_format(0.827, format)
= "82.70 %"

This is an example of a format string that will first multiply the number by 100 before outputting it with the format.

A number format can either be of two types: a "number" or a "mask" format.

A mask format is indicated by the first character in the format being an = sign. The # character in the mask will be replaced with the first available digit from the number. An example of a number format for a 10 digit phone number is: 

dim format as c = "=(###) ###-####"

? a5_number_format(8004511018, format)
= "(800) 451-1018"

While 'masks' are simple, 'number' formatting can be more complex. Below is a list of the special characters that can be used in a 'number' format string:

Character
Description
#

an optional digit

0

a required digit (will be output as "0" if no value in the number for the given location)

_

an optional digit (will be output as " " if no value in the number for the given location)

*

after the decimal character will cause there to be no rounding (number is output with its full precision)

]

at end of a number format (before any suffix) means round to zero (there will be no decimal value)

[

with "]" means force "0" for integer places in the number (e.g. 123 formatted with #[00] would be 100)

<

at end of a number format (before any suffix) means round decimal up, before "]" is the round up equivalent of "["

>

at end of a number format (before any suffix) means round decimal down, before "]" is the round down equivalent of "["

-/-

display decimals as fractions

After optional conditions and number processing expressions have been removed from the format string, any non-special characters at the beginning and end of the format string are placed into the prefix or suffix. If a format string does not contain multiple formats for positive and negative values, a - (minus sign) will be prefixed the result if the number is negative.

Format String Example 1

This example format shows using a " " to separate thousands and a "," for the decimal, rounding to two decimal places, and padding with "0" for two decimal places

dim format as c = "# ##0,00"
dim number as n = 1256.2

? a5_number_format(number, format)
= "1 256,20"

Format String Example 2

This example format shows padding the integer part with a "0" and using a "." for the decimal. It also rounds down the number to two decimal places.

dim format as c = "0.00>"
dim number as n = .257

? a5_number_format(number, format)
= "0.25"

Format String Example 3

This example format shows clipping to two integer places and using a "," as thousands separator.

dim format as c = "#,#[00]"
dim number as n = 1256.2

? a5_number_format(number, format)
= "1,300"

Format String Example 4

This example format shows clipping to two integer places, rounding down, and using a "," as thousands separator.

"dim format as c = "#,#>00]"
dim number as n = 1256.2

? a5_number_format(number, format)
= "1,200""

Format String Example 5

This example format shows use a "." for the decimal and a "," for the thousands separator, don't round the decimal.

dim format as c = "#,##0.*"
dim number as n = 1256.2256

? a5_number_format(number, format)
= "1,256.2256"

Format String Example 6

This example format shows rounding down to two decimal places and rendering the decimal as a fraction in the suffix.

dim format as c = "0.##> and -/-"
dim number as n = 1.256

? a5_number_format(number, format)
= "1 and 1/4"

Format String Example 7

This example format shows creating multiple format strings for positive, negative, and zero values. The thousands separator is "," and the decimal character is ".". The number is rounded to 2 places. Negative values are enclosed in parentheses. The zero value is output as "------".

dim format as c = "$#,##0.00;$ (#,##0.00);------"

? a5_number_format(1256.2, format)
= "$1,256.20"

? a5_number_format(-126.887, format)
= "$ (126.89)"

? a5_number_format(0, format)
= "------"

Format String Example 8

This example format shows rendering the number with a custom suffix based on a condition. For example, if the number is 4, the output value is (Good). If the number is 1, the output value is (Bad).

dim format as c = "if(n>=4)# (Good);if(n>=2)# (Average);# (Bad)"

? a5_number_format(4,format)
= "4 (Good)"

? a5_number_format(3,format)
= "3 (Average)"

? a5_number_format(1,format)
= "1 (Bad)"